home *** CD-ROM | disk | FTP | other *** search
/ Aminet 1 (Walnut Creek) / Aminet - June 1993 [Walnut Creek].iso / aminet / util / pack / xfh132.lzh / XFH / XFH.doc < prev    next >
Text File  |  1993-01-19  |  15KB  |  344 lines
  1. ----------------------------------------------------------------------------
  2.  
  3.                XFH-Handler 1.32
  4.  
  5.        Copyright (C) 1991, 1992, 1993 Kristian Nielsen.
  6. ----------------------------------------------------------------------------
  7.  
  8.  
  9.     This program is free software; you can redistribute it and/or modify
  10.     it under the terms of the GNU General Public License as published by
  11.     the Free Software Foundation; either version 2 of the License, or
  12.     (at your option) any later version.
  13.  
  14.     This program is distributed in the hope that it will be useful,
  15.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  16.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17.     GNU General Public License for more details.
  18.  
  19.     You should have received a copy of the GNU General Public License
  20.     along with this program; if not, write to the Free Software
  21.     Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  22.  
  23.  
  24. Comments, suggestions and bug reports are welcome. I can be reached as
  25.  
  26.    Kristian Nielsen
  27.    Groenjordskollegiet
  28.    room 6111
  29.    Groenjordsvej
  30.    DK-2300 Koebenhavn S
  31.    Denmark.
  32.  
  33.    E-Mail: bombadil@diku.dk
  34.  
  35.  
  36. Legal Issues
  37. ------------
  38.  
  39. This program as a whole is distributed under the GNU General Public
  40. License. However, some of the contained material carries different
  41. legal status. In particular, this product includes software developed
  42. by the University of California, Berkeley and its contributors.
  43. Details appear in each individual file in the source directories.
  44.  
  45. The "XFH" commodity was written by
  46.  
  47.    Nicola Salmoria
  48.    Via Piemonte 11
  49.    53100 Siena   ITALY
  50.  
  51.    E-Mail: MC6489@mclink.it
  52.  
  53. This program (the commodity with icons and mountlists) is freely
  54. distributable as long as the archive remains intact, and only a
  55. nominal fee is charged for its distribution. However, it is still
  56. provided "AS IS" without warranty of any kind, either expressed or
  57. implied. By using it, you agree to accept the entire risk as to the
  58. quality and performance of the program.
  59.  
  60.  
  61. Changes since the previous versions
  62. -----------------------------------
  63.  
  64. XFH has changed quite a bit since the last release (v1.12). Important
  65. changes include:
  66.  
  67.  - XFH is now distributed with full source code (for GCC).
  68.  - The dreaded 'ExNext() / ExAll() bug with filenotes has been fixed.
  69.  - Much improved user interface: Gui 'front panel' (by Nicola
  70. Salmoria), improved mountlist control.
  71.  - Arexx interface for setting options after mounting the handler.
  72.  - Support for MODE_READWRITE (appending to files).
  73.  
  74.  
  75. Overview
  76. --------
  77.  
  78. XFH-handler is a DOS handler which uses xpkmaster.library to provide
  79. transparent access to compressed files in a given directory or partition.
  80. All compression/decompression is done automatically by the handler when files
  81. are read or written. Compression is optional and may be switched at any time,
  82. allowing for fine control over storage of data. The compression method may be
  83. changed at will. Decompression is always automatic, you don't have to care
  84. about which compressor was used to create the files.
  85.  
  86. This version of XFH is designed to work with Xpk, the data compression
  87. standard. You will need Xpk to use XFH. Most users should receive XFH as part
  88. of the Xpk distribution.
  89.  
  90. [Notes for users of previous versions of XFH: The way the handler is mounted
  91. has changed somewhat since v1.12 in order to make it simpler to use; you
  92. cannot just replace the binary in L: and go. This doc file does not mention
  93. the old option files, but they can still be used if you want to. Refer to the
  94. file "advanced_usage.doc". Also note that XFH now supports updating of
  95. existing files, something that a lot of users have requested.]
  96.  
  97.  
  98. Installation
  99. ------------
  100.  
  101. This doc file is intended for Workbench 2.0 or later. If you are using
  102. Wb 1.x, refer to "advanced_usage.doc". That file contains also information
  103. which may be useful to the advanced user.
  104.  
  105. We have tried to make the installation of XFH as easy as possible, but it
  106. still isn't a trivial task. Please read this paragraph carefully.
  107.  
  108. First of all, you will need to have xpkmaster.library installed
  109. (xpkmaster.library is distributed as part of Xpk). Refer to xpkmaster
  110. documentation for installation. Version 2.2 (or any later version) of
  111. xpkmaster.library is suggested, since previous versions contain some bugs
  112. which may make XFH behave incorrectly.
  113.  
  114. Then, copy "XFH-Handler" to your L: directory, and drag "XFH" into the
  115. Wbstartup drawer. XFH is a commodity, so as usual you will want to change
  116. the CX_POPUP ToolType from YES to NO to avoid having the window open
  117. everytime you boot.
  118.  
  119. Now you have to decide which partition you want to install XFH upon. Of
  120. course you can choose more than one partition, but with this version of XFH
  121. you shouldn't use the boot partition unless you really know what you are
  122. doing.
  123. >> NEVER COMPRESS XFH-HANDLER, XPKMASTER.LIBRARY, MOUNT, OR ANY OTHER FILE
  124. NEEDED TO MAKE XFH WORK!!!!!! <<
  125.  
  126. You are not limited to install on full partitions; you can choose any
  127. directory, but usage on a whole partition is probably the more immediate and
  128. useful. Here, we will assume installation on a whole partition. Installation
  129. over a directory is accomplished in a similar way, or by modifying the
  130. mountlist entry as explained in "advanced_usage.doc".
  131.  
  132. If you are using Workbench 2.1 or later, drag the icon "XDH1" from the
  133. "Workbench2.1+" drawer to the "Devs/DOSDrivers" drawer in your boot
  134. partition.  As its name suggests, XDH1 will work on your DH1 partition.
  135. To choose a different partition, just rename the icon; for example, "XJH2"
  136. will refer to JH2:, and so on (in fact any letter will work, not just
  137. 'X').  You can also use assigned names; for example, let's say you have
  138. assigned DOCS: to DH2:text/docs, then a copy of the icon named "XDOCS"
  139. will create an XFH task using that directory. To create multiple XFH
  140. partitions, use the Workbench 'Copy' command to duplicate the "XDH1" icon
  141. and rename it appropriately (ie. to "XDH2"). No other changes are needed.
  142.  
  143. If you are not using Wb 2.1 yet, you will have to append the sample entry
  144. "devs/mountlist.xdh1" to your "DEVS:Mountlist" file (appending one copy for
  145. each XFH partition you wish to use). The same considerations made before
  146. apply: to change the target partition, edit the mountlist and change the
  147. XDH1: line appropriately. Then edit the file "S:User-Startup" and add lines
  148. like
  149.  
  150.     Mount XDH1:
  151.  
  152. to automatically mount the XFH partitions at boot time.
  153.  
  154. If you don't like names like XDH1, refer to "advanced_usage.doc" for a way
  155. to use a name of your choice (by modifying the mount entry).
  156.  
  157.  
  158. When mounted, XFH will display a new icon on your Workbench screen. For
  159. example, let's say that your DH1: partition is labelled "DATA"; XFH will call
  160. its partition XFH_DATA. After the first installation, you may relabel the
  161. volume as usual (XFH will use a file called '.xfhrc' in its root
  162. directory to preserve the volume name across reboots).
  163.  
  164. The first step of installation is completed. Now reset and check that
  165. everyting works correctly. Next steps assume that you have rebooted and
  166. everything was ok.
  167.  
  168.  
  169. By default, XFH doesn't compress files. To do that, invoke the XFH commodity
  170. by using the hotkey (default is control alt x) or by double-clicking its
  171. icon.  You will be shown a list of all mounted XFH partitions. Choose one,
  172. and activate the "Compression" checkbox. Now click on "Select Compressor..."
  173. button, and you will see a list of available Xpk compressors. Select your
  174. favourite compressor and efficiency and click on "OK". Currently, the best
  175. choice is probably NUKE, since it features good compression percentage and
  176. very fast decompression.
  177.  
  178. The "Low Memory" checkbox, when activated, tells XFH to reduce memory usage
  179. as much as possible, even if that means reducing speed or compression
  180. efficiency (this option is not fully implemented in the current version of
  181. XFH-Handler).
  182.  
  183.  When you have set up all the partitions, select "Save" from the
  184. "Project" menu if you want to make the changes permanent, and click in the
  185. close gadget to hide the window ("Save" will store the settings in the .info file of the commodity).
  186.  
  187. Now installation should be finished! Try to copy something to XDH1:, and try
  188. from CLI to 'list' it in DH1: and in XDH1: to see if it has actually been
  189. compressed (of course the file in DH1: should be shorter than the file which
  190. is seen thru XDH1:).
  191.  
  192. Hint: if you want to compress all the files in your new XFH partition, the
  193. faster way is to make a backup and restore of XDH1:.
  194.  
  195.  
  196. Limitations
  197. -----------
  198.  
  199. It should be stressed that a given XFH partition binds to a volume,
  200. not to a device. This has consequences if XFH is used on a removable
  201. media like a flopy disk. For example, trying to use XDF0 to access DF0
  202. will work, but it will use the disk that was in the drive at the time
  203. it was mounted and will not recognise a newly inserted disk.
  204.  
  205.    The figures reported by the shell 'Info' command are somewhat
  206. strange.  The problem is that it isn't really possible to give
  207. sensible figures for 'NumBlocks' and 'NumBlocksUsed' (except scanning
  208. the entire XFH partition which would be ridicously slow). Currently,
  209. their values are the same as those for the underlying file system.
  210.  
  211.  
  212. Suggestions
  213. -----------
  214.  
  215. Remember that, in this release of XFH-Handler, the decompressed file has to
  216. stay in memory for all the time the file is open. If you are low on memory,
  217. do not compress large files.
  218. Do not compress files which stay open for a long time.
  219. If you are using a printer spooler which creates temporary files on the hard
  220. disk (like PrintManager by Nicola Salmoria), make sure they are not
  221. automatically compressed by XFH (either turn compression off, or use DH1:
  222. instead of XDH1:).
  223.  
  224. You may not want to have both DATA and XFH_DATA displayed as volumes on the
  225. Workbench. To avoid that, edit "S:User-Startup" and add the line
  226.  
  227.     Assign DATA: DISMOUNT
  228.  
  229. Moreover, since you may have references to DATA: (for example some assigns)
  230. you may want to add this line also
  231.  
  232.     Assign DATA: XDH1:
  233.  
  234. which will reroute every later access to the XFH partition.  Note that to do
  235. this trick, the label of DH1: must *NOT* be DH1 or any other name conflicting
  236. with a device name. If it is your case, relabel the volume.  After the
  237. DISMOUNT trick, you will always access the XFH partition from Workbench, but
  238. you will still be able to use both DH1: and XDH1: from CLI.
  239.  
  240. When doing backups, use DH1:, not XDH1:. This way you will use the
  241. compressed data, thus requiring less disks. If your backup program provides
  242. compression, turn the option off, since it will only slow things down.
  243. Remember also to RESTORE to DH1:, or you will end up with a useless
  244. partition!
  245.  
  246.  
  247. Future Enhancements
  248. -------------------
  249.  
  250. The following are a few loose ideas that may sometime be realised in future
  251. versions of XFH:
  252.  
  253.  - Support for other file formats. XFH is currently dependent on Xpk for
  254. operation; however original aim was (and still is) a general compressor
  255. front-end supporting Xpk, Zoo, Lharc, Lha etc.
  256.  
  257.  - Support for custom formats through AREXX. This would make it possible to
  258. write simple AREXX scripts that are called by XFH each time a request is made
  259. to open a file that XFH does not recognise. The script can then take over if
  260. it can handle the file and call the appropriate conversion programs. Thus,
  261. one could take for example a standard gif-to-iff converter and write a simple
  262. AREXX script that would make DeluxePaint suddenly read GIF pictures
  263.  
  264.  - Setting of options individually for specific directories and/or
  265. files (using AmigaDOS pattern matching). This would make it possible
  266. to specify that files named '#?.lzh' must not be compressed, or that
  267. directory listnings of ':net/uucp/news/' should not report the correct
  268. file sizes (for speedup).
  269.  
  270.  - Making the handler multi-treaded (like the ROM file systems)
  271. (multi-treadedness means that a large Read()-request won't block a simple CD
  272. command).
  273.  
  274.  - Implementing asyncronous I/O for compression and decompression
  275. (overlapping CPU time with IO time for large speedups).
  276.  
  277.  
  278. Acknowledgments
  279. ---------------
  280.  
  281. XFH owes a lot to all the people that have helped me during development with
  282. discussions, criticism, suggestions, bug reports etc. (not to mention the
  283. steady demands for new versions when I was a bit slow bringing them out...).
  284. I am especially indebted to Nicola Salmoria who wrote the nice gui front-end
  285. to XFH, wrote most of this doc file and spent a lot of time discussing the
  286. user interface of XFH with me. Many of the improvements in user-friendliness
  287. since XFH 1.0 should be attributed to Nicola; any remaining inconveniences or
  288. bugs are entirely due to me. My thanks should also go to Urban D. Müller for
  289. helping me start the whole concept of the XFH back in the summer of 1991 -
  290. without his help the XFH is not likely to have been realised.
  291.  
  292. XFH has been developed concurrently with my studies at the University of
  293. Copenhagen, Department of Computer Science. The institute kindly provides
  294. students with access to electronic mail and news; this also has been
  295. essential in the creation of XFH.
  296.  
  297. Program history
  298. ---------------
  299.  
  300. (In the list, an asterix ('*') denotes BETA version that have not been
  301. released and should not be used).
  302.  
  303. V1.00   Initial release.
  304. V1.00a  Bug in XObjExamine() fixed (it sometimes got the name of the root
  305.         dir wrong). Thanks to Matthias Scheler for reporting this bug.
  306. V1.00b  XFH: now obtains the values returned by ACTION_INFO and
  307.         ACTION_DISK_INFO from the underlying file system. This should
  308.         help problems with 'zero size file system' as experienced with
  309.         earlier versions of MFR for example. Thanks to Keith H. Brown
  310.         for pointing my attention to this problem.
  311. V1.10*  Beta version implementing option files and automatic compression.
  312. V1.11*  Beta with Xpk password support.
  313. V1.12   New XPKPRIORITY option. Also fixes bugs with bad volume names and a 
  314.         msgport that was unnessesarely public; thanks to Nicola Salmoria 
  315.         for telling me about these problem. 
  316. V1.20*  First beta with gui and Arexx support.
  317. V1.21*  - Bug fix: Write() to a compressed file opened for reading now
  318.         fails with a return value of -1L (it used to return 0). Thanks to
  319.         Stefan Boberg for pointing me to this problem.
  320.         - Bug fix: Very nasty bug with file notes that caused XFH to crash
  321.         the system (happened because dos.library does not preserve the
  322.         fib->fib_Comment field between calls to ExNext()). Thanks to
  323.         Anders Holmér for taking the bother sending me "snail mail" to
  324.         let me know of this problem.
  325. V1.22*    Enhanced gui support. XFH now mounts as a handler (instead of as a
  326.     disk-device based file system). Setting of options in mountlist.
  327. V1.23*    Minor bugfixes; some options to help compatibility with various
  328.     programs.
  329. V1.30*    First version with support for MODE_READWRITE. XFH will now retain
  330.     protection flags, filenotes and file dates when compressing files.
  331.     ALLOWAPPEND and COMPRESSREADWRITE option. Write() to MODE_OLDFILE
  332.     files.
  333. V1.31*    ACTION_RENAME_DISK; PORTNAME option; minor bug fixes.
  334. V1.32     Full source provided now under GNU GPL. Source now uses RCS.
  335.     Changed default for option ALLOWAPPEND to ON. Also changed
  336.     option KILLSTARTUP to ON per default (the enforcer hits in
  337.     Format etc. were too bad).
  338.  
  339.  
  340. [Local variables for Emacs:]
  341. Local Variables:
  342. mode: text
  343. End:
  344.